feat(ui): enforce minimum clerk-js version compatibility by bratsos · Pull Request #7667 · clerk/javascript

bratsos · 2026-01-23T19:40:29Z

Add runtime version check in ClerkUi constructor to detect incompatible @clerk/clerk-js versions. In development instances, logs a warning; in production, throws ClerkRuntimeError with actionable upgrade guidance.

Also moves shared version utilities to @clerk/shared/utils.

Description

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

New Features
- Runtime version compatibility check for Clerk.js during UI initialization (throws in development, warns in production).
- Added a convenience API to check if a version meets a minimum requirement.
- Introduced a new minimum-supported Clerk.js version constant.
Tests
- Added comprehensive tests covering version checks, UI init behaviors (dev vs prod), pre-releases, and edge cases.
Chores
- Added changeset and updated bundle size threshold.

changeset-bot · 2026-01-23T19:40:34Z

🦋 Changeset detected

Latest commit: a3c8712

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 20 packages

Name	Type
@clerk/shared	Minor
@clerk/ui	Minor
@clerk/react	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/vue	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-01-23T19:40:35Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Feb 3, 2026 6:02pm

nikosdouvlis · 2026-01-27T11:13:25Z

packages/ui/src/constants.ts

@@ -1,3 +1,5 @@
+export const MIN_CLERK_JS_VERSION = '5.112.0';


Is 5.112.0 the correct version here or should this be pinned to 6.0.0 since thats the major for core 3? The tests seem to use 6.0.0 as the expected minimum which made me wonder if this was intentional or if the constant just needs updating.

I think the version when we added ModuleManager/ClerkUi was 5.112.0 so in theory this could be the minimum clerk js version. But we can also arbitrarily set this to 6.0.0 to make it available only on Core3. WDYT?

I updated this to 6.0.0 73ebcb5

nikosdouvlis · 2026-01-27T11:13:25Z

packages/ui/src/ClerkUi.ts

+        logger.warnOnce(incompatibilityMessage);
+      } else {
+        throw new ClerkRuntimeError(incompatibilityMessage, { code: 'clerk_ui_version_mismatch' });
+      }


Should this be the other way around? Typically we want to fail fast in development (so devs catch issues early) but be more lenient in production (to avoid breaking user-facing apps). The current behavior warns in dev (easy to miss) but throws in prod (could cause outages).

Yeah that makes more sense. I went with "You don't want a mismatch on production" as you may end up with weird-looking UI, but I agree. 4e1751d

nikosdouvlis · 2026-01-27T11:13:25Z

packages/ui/src/ClerkUi.ts

+        `@clerk/ui@${ClerkUi.version} requires @clerk/clerk-js@>=${MIN_CLERK_JS_VERSION}, ` +
+        `but found an incompatible version${clerkVersion ? ` (${clerkVersion})` : ''}. ` +
+        `Please upgrade @clerk/clerk-js (or your framework SDK) to a compatible version.`;
+    }


Looking at clerk-js, it always instantiates ClerkUi with new ModuleManager(), and clerkVersion comes from the Clerk instance which should always have its version set. Is there a scenario where ClerkUi would be instantiated without a moduleManager or without knowing the clerkVersion? If this is just defensive coding thats fine, but if theres an actual use case Im curious what it is :)

It's just defensive to future-proof us from a mistake. I thought about all different scenarios with pinned/hotloaded clerk-js and before/after we introduced moduleManager/ClerkUi and I don't think you land in this case right now, but you never know in the future.

nikosdouvlis · 2026-01-27T11:13:33Z

~~this PR adds a new feature to @clerk/ui and @clerk/shared but I dont see a changeset for it. Should we add one describing the new minimum version check behavior?~~

This is fine

coderabbitai · 2026-01-30T16:41:58Z

📝 Walkthrough

Walkthrough

This pull request adds runtime Clerk.js SDK version validation to ClerkUi: a new constant MIN_CLERK_JS_VERSION ('6.0.0') and an exported isVersionAtLeast function in versionCheck were introduced. ClerkUi's constructor now parses the detected @clerk/clerk-js version and, if incompatible or unparseable, throws a ClerkRuntimeError (code clerk_ui_version_mismatch) in development or logs a single warning in production. Tests for the new checks and version comparisons were added. A minor import reorder in parseVersionRange.ts and a changeset documenting package version bumps were also included.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: enforcing minimum clerk-js version compatibility with runtime checks in ClerkUi.
Linked Issues check	✅ Passed	The PR successfully implements minimum clerkjs SDK version enforcement in ClerkUi with runtime checks, version comparison utilities, and comprehensive error handling as required.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing version compatibility checks: utilities in shared, version validation in ClerkUi, constants, tests, and bundle size adjustment for the slightly larger code.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Important

Action Needed: IP Allowlist Update

If your organization protects your Git platform with IP whitelisting, please add the new CodeRabbit IP address to your allowlist:

✨ 136.113.208.247/32 (new)
34.170.211.100/32
35.222.179.152/32

Reviews will stop working after February 8, 2026 if the new IP is not added to your allowlist.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

packages/ui/src/__tests__/ClerkUi.test.ts

pkg-pr-new · 2026-02-02T20:50:27Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7667

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@7667

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@7667

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@7667

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@7667

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7667

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@7667

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@7667

@clerk/express

npm i https://pkg.pr.new/@clerk/express@7667

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@7667

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@7667

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@7667

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@7667

@clerk/react

npm i https://pkg.pr.new/@clerk/react@7667

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@7667

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@7667

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@7667

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@7667

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@7667

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@7667

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@7667

commit: a3c8712

Add runtime version check in ClerkUi constructor to detect incompatible @clerk/clerk-js versions. In development instances, logs a warning; in production, throws ClerkRuntimeError with actionable upgrade guidance.

github-actions bot added the react label Jan 23, 2026

bratsos force-pushed the alexbratsos/user-4102-implement-minimum-clerkjs-sdk-version-in-clerkui branch from f6578d0 to 682ea78 Compare January 23, 2026 20:44

vercel bot deployed to Preview January 23, 2026 20:45 View deployment

Base automatically changed from brkalow/sacramento to main January 23, 2026 21:05

bratsos force-pushed the alexbratsos/user-4102-implement-minimum-clerkjs-sdk-version-in-clerkui branch from 682ea78 to a033dda Compare January 26, 2026 17:07

github-actions bot added the core-3 label Jan 26, 2026

vercel bot deployed to Preview January 26, 2026 17:08 View deployment

bratsos force-pushed the alexbratsos/user-4102-implement-minimum-clerkjs-sdk-version-in-clerkui branch from a033dda to d1d402b Compare January 26, 2026 17:25

vercel bot deployed to Preview January 26, 2026 17:26 View deployment

nikosdouvlis reviewed Jan 27, 2026

View reviewed changes

vercel bot deployed to Preview January 29, 2026 15:45 View deployment

bratsos marked this pull request as ready for review January 30, 2026 16:35

bratsos requested a review from nikosdouvlis January 30, 2026 17:15

jacekradko reviewed Jan 30, 2026

View reviewed changes

packages/ui/src/__tests__/ClerkUi.test.ts Outdated Show resolved Hide resolved

bratsos force-pushed the alexbratsos/user-4102-implement-minimum-clerkjs-sdk-version-in-clerkui branch from 4e1751d to 73ebcb5 Compare February 2, 2026 20:47

vercel bot deployed to Preview February 2, 2026 20:47 View deployment

vercel bot deployed to Preview February 2, 2026 21:34 View deployment

jacekradko approved these changes Feb 2, 2026

View reviewed changes

vercel bot deployed to Preview February 3, 2026 13:04 View deployment

vercel bot deployed to Preview February 3, 2026 14:23 View deployment

vercel bot deployed to Preview February 3, 2026 14:47 View deployment

bratsos added 4 commits February 3, 2026 18:57

feat(ui): enforce minimum clerk-js version compatibility

c1d1334

Add runtime version check in ClerkUi constructor to detect incompatible @clerk/clerk-js versions. In development instances, logs a warning; in production, throws ClerkRuntimeError with actionable upgrade guidance.

fixup! feat(ui): enforce minimum clerk-js version compatibility

b7b9c7a

fixup! feat(ui): enforce minimum clerk-js version compatibility

b790207

chore: add changeset

3a8206a

chore(ui): bump bundle size limit

a3c8712

bratsos force-pushed the alexbratsos/user-4102-implement-minimum-clerkjs-sdk-version-in-clerkui branch from 306822c to a3c8712 Compare February 3, 2026 18:01

vercel bot deployed to Preview February 3, 2026 18:02 View deployment

bratsos merged commit fd69edb into main Feb 3, 2026
40 checks passed

bratsos deleted the alexbratsos/user-4102-implement-minimum-clerkjs-sdk-version-in-clerkui branch February 3, 2026 18:16

nikosdouvlis pushed a commit that referenced this pull request Feb 12, 2026

feat(ui): enforce minimum clerk-js version compatibility (#7667)

7e91ac8

		@@ -1,3 +1,5 @@
		export const MIN_CLERK_JS_VERSION = '5.112.0';

Conversation

bratsos commented Jan 23, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nikosdouvlis Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

bratsos Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

bratsos Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

nikosdouvlis Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

bratsos Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

nikosdouvlis Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

bratsos Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

nikosdouvlis commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

Uh oh!

pkg-pr-new bot commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bratsos commented Jan 23, 2026 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Jan 23, 2026 •

edited

Loading

vercel bot commented Jan 23, 2026 •

edited

Loading

nikosdouvlis commented Jan 27, 2026 •

edited

Loading

coderabbitai bot commented Jan 30, 2026 •

edited

Loading

pkg-pr-new bot commented Feb 2, 2026 •

edited

Loading